<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="umsroot.css">
<TITLE>
Source Structure
</TITLE>
</HEAD>
<BODY >
<A HREF="umsroot030.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot028.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot032.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc64">6.3</A>&nbsp;&nbsp;Source Structure</H2><UL>
<LI><A HREF="umsroot031.html#toc35">Clauses and Predicates</A>
<LI><A HREF="umsroot031.html#toc36">Compilation and Modules</A>
<LI><A HREF="umsroot031.html#toc37">Incrementality</A>
</UL>


The compiler normally reads files from beginning to end, but the
file end can also be simulated with a clause
<PRE CLASS="verbatim">
end_of_file.
</PRE>When reading from a terminal/console, the end of the input can be
marked by CTRL-D (in Unix-like systems) or CTRL-Z+RETURN on Windows.<BR>
<BR>
When reading program source, the compiler distinguishes
<I>clauses</I>, <I>directives</I> and <I>file queries</I>.
Directives are terms with main functor
<B>:-/1</B>
while file queries have the main functor
<B>?-/1</B>. Everything else is a program clause (see Appendix <A HREF="umsroot139.html#chapsyntax">A</A>)<BR>
<BR>
The differences between a directive and a file query are as follows:
<UL CLASS="itemize"><LI CLASS="li-itemize">
File queries are general goals, and are executed when the program
	is loaded, i.e. when compiling with the load-option set to <B>all</B>,
	or when loading a compiled file. When compiling without loading,
	they are ignored.
<LI CLASS="li-itemize">Directives can be general goals, in which case they are executed
	while the program is being compiled, and also when a compiled
	program is loaded.
<LI CLASS="li-itemize">Some directives are not goals, but are interpreted by the compiler
	(or other source processing tool), e.g. module-directives or
	pragmas. These should not be combined with general goals in
	the same directive.
</UL>
Directives and file queries should succeed and should only have a single
solution. No results are printed by the system, failure leads to a warning,
and an error condition will cause compilation to abort.<BR>
<BR>
<A NAME="toc35"></A>
<H3 CLASS="subsection"><A NAME="htoc65">6.3.1</A>&nbsp;&nbsp;Clauses and Predicates</H3>

All other input terms are interpreted as clauses to be compiled.
A sequence of consecutive clauses whose heads have the same
functor is interpreted as one predicate. Normally, all clauses for
one predicate should be consecutive in the source. If this is not the
case, the compiler issues a warning and ignores the new clauses.<BR>
<BR>
To change this behaviour, a
<A HREF="../bips/kernel/compiler/discontiguous-1.html"><B>discontiguous/1</B></A><A NAME="@default223"></A>
declaration must be used. The clauses are then collected and compiled
as a whole once the end of the source unit (file or module) has been reached.<BR>
<BR>
To add clauses for a predicate incrementally though several independent
compiler invocations is only possible by declaring the corresponding
predicate as <A HREF="../bips/kernel/dynamic/dynamic-1.html"><B>dynamic/1</B></A><A NAME="@default224"></A>,
see Chapter <A HREF="umsroot062.html#chapdynamic">11</A>.<BR>
<BR>
<A NAME="toc36"></A>
<H3 CLASS="subsection"><A NAME="htoc66">6.3.2</A>&nbsp;&nbsp;Compilation and Modules</H3>

In the absence of module-directives
(<A HREF="../bips/kernel/modules/module-1.html"><B>module/1</B></A><A NAME="@default225"></A>,
<A HREF="../bips/kernel/modules/module-3.html"><B>module/3</B></A><A NAME="@default226"></A>)
within the file, the
file content is compiled into the module from which compile/1,2 itself
was called. This context module may be modified using the @/2 notation,
i.e. compile(File,Options)@Module. Existing static predicates will
be redefined, and clauses for dynamic predicates appended to the
existing ones (unless the 'load' option requests otherwise).<BR>
<BR>
If the compiled file contains module directives (module/1,3), these
specify to which module(s) the subsequent code belongs. Module directives
are effective from the point where they occur until the next module
directive, or until the end of file. If a module directive refers
to a module that already exists, this module is erased and redefined
(unless the 'load' option requests otherwise).<BR>
<BR>
It is generally recommended to follow the <EM>one file - one module</EM>
convention, and to make the base name of the file identical to the
module name. In rare cases, it may make sense to have an auxiliary
module in the same file as the main module. This is allowed, and
every new module directive terminates the previous module.<BR>
<BR>
To spread the code for one module over several files, use a top-level
file containing the module directive plus one or more include-directives
(section <A HREF="umsroot032.html#secinclude">6.4.3</A>) for the component files.<BR>
<BR>
<A NAME="toc37"></A>
<H3 CLASS="subsection"><A NAME="htoc67">6.3.3</A>&nbsp;&nbsp;Incrementality</H3>

When it encounters a
<A HREF="../bips/kernel/modules/module-1.html"><B>module/1</B></A><A NAME="@default227"></A>/
<A HREF="../bips/kernel/modules/module-3.html"><B>module/3</B></A><A NAME="@default228"></A> directive
the compiler first erases previous contents of this module,
if there was any, before starting to compile predicates
into it. This means that in order to incrementally add predicates
to a module, the module directive cannot be used
because the previous contents of the module would be destroyed.
Instead, the construct <B>compile(File)@Module</B> must be used.<BR>
<BR>
<HR>
<A HREF="umsroot030.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot028.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot032.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
